home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / tools / indent.lha / indent / indent.man < prev    next >
Text File  |  1992-07-06  |  16KB  |  400 lines
  1.  
  2.  
  3.  
  4.      INDENT(1)             A/UX (July 14, 1989)              INDENT(1)
  5.  
  6.  
  7.  
  8.      NAME
  9.           indent - indent and format C program source
  10.  
  11.      SYNOPSIS
  12.           indent  [ input-file [ output-file ] ] [ -bad | -nbad ]
  13.                  [ -bap | -nbap ] [ -bbb | -nbbb ] [ -bc | -nbc ]
  14.                  [ -bl ] [ -br ] [ -brr ] [ -cn ] [ -cdn ]
  15.                  [ -cdb | -ncdb ] [ -ce | -nce ] [ -cin ] [ -clin ]
  16.                  [ -ccin ] [ -dn ] [ -din ] [ -fc1 | -nfc1 ] [ -in ]
  17.                  [ -ip | -nip ] [ -ln ] [ -lcn ] [ -lp | -nlp ]
  18.                  [ -pcs | -npcs ] [ -npro ] [ -prs | -nprs ]
  19.                  [ -psl | -npsl ] [ -sc | -nsc ] [ -sob | -nsob ]
  20.                  [ -st ] [ -tabsn ] [ -troff ] [ -v | -nv ] [ -+ ]
  21.  
  22.  
  23.      DESCRIPTION
  24.           Indent is a C program formatter.  It reformats the C program
  25.           in the input-file according to the switches.  The switches
  26.           which can be specified are described below. They may appear
  27.           before or after the file names.
  28.  
  29.           NOTE: If you only specify an input-file, the formatting is
  30.           done 'in-place', that is, the formatted file is written back
  31.           into input-file and a backup copy of input-file is written
  32.           in the current directory.  If input-file is named
  33.           '/blah/blah/file', the backup file is named file.BAK.
  34.  
  35.           If output-file is specified, indent checks to make sure it
  36.           is different from input-file.
  37.  
  38.      OPTIONS
  39.           The options listed below control the formatting style
  40.           imposed by indent.
  41.  
  42.           -bap,-nbap     If -bap is specified, a blank line is forced
  43.                          after every procedure body.  Default:  -nbap.
  44.  
  45.           -bad,-nbad     If -bad is specified, a blank line is forced
  46.                          after every block of declarations.  Default:
  47.                          -nbad.
  48.  
  49.           -bbb,-nbbb     If -bbb is specified, a blank line is forced
  50.                          before every block comment.  Default:  -nbbb.
  51.  
  52.           -bc,-nbc       If -bc is specified, then a newline is forced
  53.                          after each comma in a declaration. -nbc turns
  54.                          off this option.  The default is -bc.
  55.  
  56.           -br,-bl,-brr   Specifying -bl lines up compound statements
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 3/16/92)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      INDENT(1)             A/UX (July 14, 1989)              INDENT(1)
  71.  
  72.  
  73.  
  74.                          like this:
  75.                              if (...)
  76.                              {
  77.                                  code
  78.                              }
  79.                          Specifying -br (the default) makes them look
  80.                          like this:
  81.                              if (...) {
  82.                                  code
  83.                              }
  84.                          And specifying -brr makes them look like
  85.                          this:
  86.                              if (...)
  87.                                  {
  88.                                  code
  89.                                  }
  90.  
  91.           -cn            The column in which comments on code start.
  92.                          The default is 33.
  93.  
  94.           -cdn           The column in which comments on declarations
  95.                          start.  The default is for these comments to
  96.                          start in the same column as those on code.
  97.  
  98.           -cdb,-ncdb     Enables (disables) the placement of comment
  99.                          delimiters on blank lines.  With this option
  100.                          enabled, comments look like this:
  101.                               /*
  102.                                * this is a comment
  103.                                */
  104.                          Rather than like this:
  105.                               /* this is a comment */
  106.                          This only affects block comments, not
  107.                          comments to the right of code. The default is
  108.                          -cdb .
  109.  
  110.           -ce,-nce       Enables (disables) forcing 'else's to cuddle
  111.                          up to the immediatly preceding }.  The default
  112.                          is -ce.
  113.  
  114.           -cin           Sets the continuation indent to be n.
  115.                          Continuation lines will be indented that far
  116.                          from the beginning of the first line of the
  117.                          statement.  Parenthesized expressions have
  118.                          extra indentation added to indicate the
  119.                          nesting, unless -lp is in effect.  -ci
  120.                          defaults to the same value as -i.
  121.  
  122.           -clin          Causes case labels to be indented n tab stops
  123.                          to the right of the containing switch
  124.                          statement.  -cli0.5 causes case labels to be
  125.                          indented half a tab stop.  The default is
  126.                          -cli0 .
  127.  
  128.  
  129.  
  130.      Page 2                                          (printed 3/16/92)
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.      INDENT(1)             A/UX (July 14, 1989)              INDENT(1)
  138.  
  139.  
  140.  
  141.           -ccin          Causes case code to be indented n tab stops
  142.                          to the right of the corresponding case label.
  143.                          -cci0.5 causes case code to be indented half
  144.                          a tab stop.  The default is -cci1 .
  145.  
  146.           -dn            Controls the placement of comments which are
  147.                          not to the right of code.  The default -d1
  148.                          means that such comments are placed one
  149.                          indentation level to the left of code.
  150.                          Specifying -d0 lines up these comments with
  151.                          the code.  See the section on comment
  152.                          indentation below.
  153.  
  154.           -din           Specifies the indentation, in character
  155.                          positions, from a declaration keyword to the
  156.                          following identifier.  The default is -di16 .
  157.  
  158.           -fc1,-nfc1     Enables (disables) the formatting of comments
  159.                          that start in column 1.  Often, comments
  160.                          whose leading '/' is in column 1 have been
  161.                          carefully hand formatted by the programmer.
  162.                          In such cases, -nfc1 should be used.  The
  163.                          default is -fc1.
  164.  
  165.           -in            The number of spaces for one indentation
  166.                          level.  The default is 4.
  167.  
  168.           -ip,-nip       Enables (disables) the indentation of
  169.                          parameter declarations from the left margin.
  170.                          The default is -ip .
  171.  
  172.           -ln            Maximum length of an output line.  The
  173.                          default is 75.
  174.  
  175.           -npro          Causes the profile files, './.indent.pro' and
  176.                          '~/.indent.pro', to be ignored.
  177.  
  178.           -lp,-nlp       Lines up code surrounded by parenthesis in
  179.                          continuation lines.  If a line has a left
  180.                          paren which is not closed on that line, then
  181.                          continuation lines will be lined up to start
  182.                          at the character position just after the left
  183.                          paren.  For example, here is how a piece of
  184.                          continued code looks with -nlp in effect:
  185.                              p1 = first_procedure(second_procedure(p2, p3),
  186.                                  third_procedure(p4, p5));
  187.                          With -lp in effect (the default) the code
  188.                          looks somewhat clearer:
  189.                              p1 = first_procedure(second_procedure(p2, p3),
  190.                                                   third_procedure(p4, p5));
  191.  
  192.  
  193.  
  194.  
  195.  
  196.      Page 3                                          (printed 3/16/92)
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.      INDENT(1)             A/UX (July 14, 1989)              INDENT(1)
  204.  
  205.  
  206.  
  207.                          Inserting a couple more newlines we get:
  208.                              p1 = first_procedure(second_procedure(p2,
  209.                                                                    p3),
  210.                                                   third_procedure(p4,
  211.                                                                   p5));
  212.  
  213.           -pcs , -npcs   If true (-pcs) all procedure calls will have
  214.                          a space inserted between the name and the
  215.                          '('.  The default is -npcs
  216.  
  217.           -prs , -nprs   If true (-prs) all parentheses will have a
  218.                          space inserted after the '(' and before the
  219.                          ')'.  The default is -nprs
  220.  
  221.           -psl , -npsl   If true (-psl) the names of procedures being
  222.                          defined are placed in column 1 - their types,
  223.                          if any, will be left on the previous lines.
  224.                          The default is -psl
  225.  
  226.           -sc,-nsc       Enables (disables) the placement of asterisks
  227.                          ('*'s) at the left edge of all comments.
  228.  
  229.           -sob,-nsob     If -sob is specified, indent will swallow
  230.                          optional blank lines.  You can use this to
  231.                          get rid of blank lines after declarations.
  232.                          Default:  -nsob
  233.  
  234.           -st            Causes indent to take its input from stdin,
  235.                          and put its output to stdout.
  236.  
  237.           -Ttypename     Adds typename to the list of type keywords.
  238.                          Names accumulate:  -T can be specified more
  239.                          than once.  You need to specify all the
  240.                          typenames that appear in your program that
  241.                          are defined by typedefs - nothing will be
  242.                          harmed if you miss a few, but the program
  243.                          won't be formatted as nicely as it should.
  244.                          This sounds like a painful thing to have to
  245.                          do, but it's really a symptom of a problem in
  246.                          C: typedef causes a syntactic change in the
  247.                          language and indent can't find all typedefs.
  248.  
  249.           -tabsn         Tells indent that tabs are assumed to be at
  250.                          every n columns.  The default is -tabs8.  If
  251.                          n is less than 3 then tabs will not be used
  252.                          at all in the output.
  253.  
  254.           -troff         Causes indent to format the program for
  255.                          processing by troff.  It will produce a fancy
  256.                          listing in much the same spirit as vgrind.
  257.                          If the output file is not specified, the
  258.                          default is standard output, rather than
  259.                          formatting in place.
  260.  
  261.  
  262.  
  263.      Page 4                                          (printed 3/16/92)
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.      INDENT(1)             A/UX (July 14, 1989)              INDENT(1)
  271.  
  272.  
  273.  
  274.           -v,-nv         -v turns on 'verbose' mode, -nv turns it off.
  275.                          When in verbose mode, indent reports when it
  276.                          splits one line of input into two or more
  277.                          lines of output, and gives some size
  278.                          statistics at completion. The default is -nv.
  279.  
  280.           -+             turns on support for C++. In c++ mode, :: is
  281.                          permited in identifiers, C++ keywords are
  282.                          supported, and class definition keywords
  283.                          (public, private, etc.) are set in column 2.
  284.  
  285.      FURTHER DESCRIPTION
  286.           You may set up your own 'profile' of defaults to indent by
  287.           creating a file called .indent.pro in either your login
  288.           directory or the current directory and including whatever
  289.           switches you like.  A '.indent.pro' in the current directory
  290.           takes precedence over the one in your login directory.  If
  291.           indent is run and a profile file exists, then it is read to
  292.           set up the program's defaults.  Switches on the command
  293.           line, though, always override profile switches.  The
  294.           switches should be separated by spaces, tabs or newlines.
  295.  
  296.           Comments
  297.  
  298.           'Box' comments.  Indent assumes that any comment with a dash
  299.           or star immediately after the start of comment (that is,
  300.           '/*-' or '/**') is a comment surrounded by a box of stars.
  301.           Each line of such a comment is left unchanged, except that
  302.           its indentation may be adjusted to account for the change in
  303.           indentation of the first line of the comment.
  304.  
  305.           Straight text.  All other comments are treated as straight
  306.           text.  Indent fits as many words (separated by blanks, tabs,
  307.           or newlines) on a line as possible.  Blank lines break
  308.           paragraphs.
  309.  
  310.           Comment indentation
  311.  
  312.           If a comment is on a line with code it is started in the
  313.           'comment column', which is set by the -cn command line
  314.           parameter.  Otherwise, the comment is started at n
  315.           indentation levels less than where code is currently being
  316.           placed, where n is specified by the -dn command line
  317.           parameter.  If the code on a line extends past the comment
  318.           column, the comment starts further to the right, and the
  319.           right margin may be automatically extended in extreme cases.
  320.  
  321.           Special Comments
  322.  
  323.           Indent produces and interprets some special comments.  When
  324.           indent cannot parse the source, it prints a message on
  325.           standard error and inserts a comment into the output of the
  326.  
  327.  
  328.  
  329.      Page 5                                          (printed 3/16/92)
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.      INDENT(1)             A/UX (July 14, 1989)              INDENT(1)
  337.  
  338.  
  339.  
  340.           form
  341.                /**INDENT** ErrorMessage */
  342.  
  343.           Indent interprets several special comments as directives.
  344.           First, it makes no attempt to format lines containing the
  345.           error comment described above.
  346.  
  347.           Second, lines of the form:
  348.                /* INDENT OFF */
  349.           or
  350.                /* INDENT ON */
  351.           disable and re-enable indent formatting. Any amount of
  352.           whitespace may replace the spaces shown in the examples.
  353.  
  354.           Third, indent allows formatting controls to be included in
  355.           the source via comments of the form:
  356.                /* INDENT: arg1 arg2 arg3 ... arg4 */
  357.           The arguments given are in the same syntax as the command
  358.           line or profile file.  For example:
  359.                /* INDENT: -cli.25 -nfc1 */
  360.  
  361.           Preprocessor lines
  362.  
  363.           In general, indent leaves preprocessor lines alone.  The
  364.           only reformmatting that it will do is to straighten up
  365.           trailing comments.  It leaves imbedded comments alone.
  366.           Conditional compilation (#ifdef...#endif) is recognized and
  367.           indent attempts to correctly compensate for the syntactic
  368.           peculiarites introduced.
  369.  
  370.           C syntax
  371.  
  372.           Indent understands a substantial amount about the syntax of
  373.           C, but it has a 'forgiving' parser.  It attempts to cope
  374.           with the usual sorts of incomplete and misformed syntax.  In
  375.           particular, the use of macros like:
  376.                   #define forever for(;;)
  377.           is handled properly.
  378.  
  379.      FILES
  380.           ./.indent.pro  profile file
  381.  
  382.      BUGS
  383.           Indent has even more switches than ls.
  384.  
  385.           A common mistake that often causes grief is typing:
  386.               indent *.c
  387.           to the shell in an attempt to indent all the C programs in a
  388.           directory.  This is a really nasty thing to do.  (Think
  389.           about it.)
  390.  
  391.  
  392.  
  393.  
  394.  
  395.      Page 6                                          (printed 3/16/92)
  396.  
  397.  
  398.  
  399. /users/jrs>
  400.